プラグイン互換性 (v2.x)

このページでは、simply-xp v2 系列のリリースでプラグイン互換性をどのように維持するかを定義します。

安定性ルール

• 既存のプラグイン必須フィールド (name, initialize) は v2.x で安定です。
• プラグインが利用する既存の XPClient フィールドは v2.x でも利用できます。
• registerPlugins() は引き続き await 可能 (Promise<void>) であり、プラグインごとの独立した失敗処理を維持します。
• 既存のイベントコールバック名とその意味は v2.x で安定です。
• XpEvents.add()、Database.namespace()、Plugin.destroy()、unregisterPlugins() は v2.x で安定しています。

プラグインでは XpEvents.add() を使用してください

XpEvents.on() はコールバックオブジェクトを 1 つだけ 保持します。呼び出すと、他のプラグインやボット本体のハンドラーも含めて、以前に登録されていたものが置き換えられます。

XpEvents.add() はリスナーを追加し、それを解除する関数を返すため、プラグインとボットのコードが並行して購読できます。プラグインでは常に add() を使用し、返された関数を destroy() から呼び出してください。

const plugin = {
	name: "@simply-xp/example",
	requiredVersions: ["2"],
	initialize() {
		this._off = xp.XpEvents.add({ levelUp: (data, roles) => { /* ... */ } });
	},
	destroy() {
		this._off?.();
	},
};

許容される追加変更

• Plugin 型に新しい任意フィールドを追加できます。
• プラグイン開発向けに新しい任意のランタイムヘルパーを導入できます。
• 新しい任意コールバックやフックを追加できます。

次のメジャーまで延期される変更

次の変更にはメジャーリリースが必要です。

• 既存のプラグイン必須フィールドを削除または改名すること。
• 既存の XPClient フィールドを削除または改名すること。
• requiredVersions の一致判定の意味を壊すこと。
• プラグイン登録の失敗処理を独立失敗から fail-fast 動作へ変更すること。

バージョニングの推奨事項

v2 互換性を広く保つには、次の指定を推奨します。

• すべての v2 リリースをサポートするプラグインでは requiredVersions: ["2"]
• v2.0.x の挙動に結び付くプラグインでは requiredVersions: ["2.0"]
• 厳密に必要な場合のみ完全一致バージョンを使用する